react-perfect-scrollbar

What is react-perfect-scrollbar?

react-perfect-scrollbar is a React wrapper for the Perfect Scrollbar library, which provides a customizable and performant scrollbar for web applications. It allows developers to easily integrate custom scrollbars into their React components, enhancing the user experience with smooth scrolling and various customization options.

What are react-perfect-scrollbar's main functionalities?

Basic Usage

This code demonstrates the basic usage of react-perfect-scrollbar. It wraps a div containing some content with the PerfectScrollbar component, enabling custom scrolling for the content.

import React from 'react';
import PerfectScrollbar from 'react-perfect-scrollbar';
import 'react-perfect-scrollbar/dist/css/styles.css';

const MyComponent = () => (
  <PerfectScrollbar>
    <div style={{ height: '200px' }}>
      <p>Your content here...</p>
    </div>
  </PerfectScrollbar>
);

export default MyComponent;

Custom Styling

This example shows how to apply custom styling to the scrollbar. By adding a custom CSS class to the PerfectScrollbar component, you can style the scrollbar to match your application's design.

import React from 'react';
import PerfectScrollbar from 'react-perfect-scrollbar';
import 'react-perfect-scrollbar/dist/css/styles.css';
import './customScrollbar.css';

const MyComponent = () => (
  <PerfectScrollbar className="custom-scrollbar">
    <div style={{ height: '200px' }}>
      <p>Your content here...</p>
    </div>
  </PerfectScrollbar>
);

export default MyComponent;

Event Handling

This code demonstrates how to handle scroll events with react-perfect-scrollbar. The onScrollY prop is used to log the vertical scroll position whenever the user scrolls.

import React from 'react';
import PerfectScrollbar from 'react-perfect-scrollbar';
import 'react-perfect-scrollbar/dist/css/styles.css';

const MyComponent = () => {
  const handleScrollY = (container) => {
    console.log('Scrolled to Y:', container.scrollTop);
  };

  return (
    <PerfectScrollbar onScrollY={handleScrollY}>
      <div style={{ height: '200px' }}>
        <p>Your content here...</p>
      </div>
    </PerfectScrollbar>
  );
};

export default MyComponent;

Other packages similar to react-perfect-scrollbar

react-custom-scrollbars

react-custom-scrollbars is a popular alternative to react-perfect-scrollbar. It provides highly customizable scrollbars with support for custom rendering and styling. Compared to react-perfect-scrollbar, it offers more flexibility in terms of customization but may require more effort to set up.

simplebar-react

simplebar-react is another alternative that provides a simple and lightweight custom scrollbar solution. It focuses on ease of use and performance, making it a good choice for projects that need a straightforward custom scrollbar without extensive customization options.

react-scrollbars-custom

react-scrollbars-custom is a highly customizable scrollbar component for React. It offers a wide range of customization options, including custom rendering and styling. It is similar to react-perfect-scrollbar in terms of functionality but provides more advanced features for developers who need greater control over their scrollbars.

README

React-Perfect-Scrollbar

This is a wrapper to allow use perfect-scrollbar in React.

To read documentation for versions < 1.0, please visit v0.2.5.

Usage

Install the package npm install react-perfect-scrollbar -S Import the css file if you have loader for css files:

    import 'react-perfect-scrollbar/dist/css/styles.css';

Import the module in the place you want to use:

    import PerfectScrollbar from 'react-perfect-scrollbar'

Wrap you content in this component:

    <PerfectScrollbar>
        ... SCROLLBAR CONTENT HERE ...
    </PerfectScrollbar>

Props

The following props are accepted:

options

The optional parameters used to initialize perfect-scrollbar. For more info, please refer to https://github.com/utatti/perfect-scrollbar#options

This prop previously was called "option", but has since been renamed. If you provide "option" as a prop, it will be used unless "options" is also passed.

containerRef

Return the container ref: (ref) => void; If you want to scroll to somewhere, just update scrollTop/scrollLeft by the ref:

// Suppose you have save the containerRef to this._scrollRef
// change scroll top
this._scrollRef.scrollTop = 0;

// change scroll left
this._scrollRef.scrollLeft = 0;

component

The container component type. Default to "div". Only string is allowed.

className

The className added to container.

style

The style added to container.

onScrollY

Invoked when the y-axis is scrolled in either direction.

onScrollX

Invoked when the x-axis is scrolled in either direction.

onScrollUp

Invoked when scrolling upwards.

onScrollDown

Invoked when scrolling downwards.

onScrollLeft

Invoked when scrolling to the left.

onScrollRight

Invoked when scrolling to the right.

onYReachStart

Invoked when scrolling reaches the start of the y-axis.

onYReachEnd

Invoked when scrolling reaches the end of the y-axis (useful for infinite scroll).

onXReachStart

Invoked when scrolling reaches the start of the x-axis.

onXReachEnd

Invoked when scrolling reaches the end of the x-axis.

All the callback 'onXXXX' can accept a parameter: the ref to the scrollbar container. You can get the current scrollTop and scrollLeft from it:

    <PerfectScrollbar
        onScrollY={container => console.log(`scrolled to: ${container.scrollTop}.`)}>
        ... SCROLLBAR CONTENT HERE ...
    </PerfectScrollbar>

onSync

Invoked when PerfectScrollbar comp needs to sync the scrollbar container by invoking ps.update()(Basically, it is invoked in CDU lifecycle) and receive the internal perfect-scroll instance ps as parameter.

It is useful when you want to customize the sync logic in some scenarios, eg: debounce the invocation of ps.update().

For more detail, please refer to issue#87 and the example directory.

React.HTMLAttributes

Any attributes defined in React.HTMLAttributes can be used for the component.

Methods

The following method can be called by the component ref:

updateScroll

Update the scrollbar(e.g. recalculate the size) manually. In the following case, the scrollbar will not update automatically, which cause the scrollbar size incorrect.

class Container extends Component {
  ...
  render() {
    return (
      <ScrollBar>
        ...
       <ChildComponent />
        ...
      </ScrollBar>
    );
  }
}

class ChildComponent extends Component {
  handleClick = () => {
    this.setState({
      show: !this.state.show,
    });
  }

  render () {
    return (
      <div>
        <button onClick={this.handleClick} />
        { this.state.show ? <div /> }
      </div>
    )
  }
}

You need to call updateScroll to get the correct scrollbar size:

class Container extends Component {
  ...
  render() {
    return (
      <ScrollBar
        ref = {(ref) => { this._scrollBarRef = ref; }}
      >
        ...
       <ChildComponent
        onUpdateSize = {() => { this._scrollBarRef.updateScroll(); }}
       />
        ...
      </ScrollBar>
    );
  }
}

class ChildComponent extends Component {
  handleClick = () => {
    this.setState({
      show: !this.state.show,
    }, () => this.props.onUpdateSize());
  }

  render () {
    return (
      <div>
        <button onClick={this.handleClick} />
        { this.state.show ? <div /> }
      </div>
    )
  }
}

Example

A working example can be found in the example directory. Please run npm run example in browser. (Must run npm run build for the first time)

License

MIT